home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / man.3 / CrtCommand.3 < prev    next >
Text File  |  1995-07-17  |  11KB  |  354 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/CrtCommand.3,v 1.12 93/10/29 15:52:29 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS Tcl_CreateCommand tclc
  206. .BS
  207. .SH NAME
  208. Tcl_CreateCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo \- implement new commands in C
  209. .SH SYNOPSIS
  210. .nf
  211. \fB#include <tcl.h>\fR
  212. .sp
  213. \fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
  214. .sp
  215. int
  216. \fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
  217. .sp
  218. .VS
  219. int
  220. \fBTcl_GetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
  221. .sp
  222. int
  223. \fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
  224. .VE
  225. .SH ARGUMENTS
  226. .AS Tcl_CmdDeleteProc **deleteProcPtr
  227. .AP Tcl_Interp *interp in
  228. Interpreter in which to create new command.
  229. .AP char *cmdName in
  230. Name of command.
  231. .AP Tcl_CmdProc *proc in
  232. Implementation of new command:  \fIproc\fR will be called whenever
  233. \fIcmdName\fR is invoked as a command.
  234. .AP ClientData clientData in
  235. Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
  236. .AP Tcl_CmdDeleteProc *deleteProc in
  237. Procedure to call before \fIcmdName\fR is deleted from the interpreter;
  238. allows for command-specific cleanup.  If NULL, then no procedure is
  239. called before the command is deleted.
  240. .AP Tcl_CmdInfo *infoPtr in/out
  241. .VS
  242. Pointer to structure containing various information about a
  243. Tcl command.
  244. .VE
  245. .BE
  246.  
  247. .SH DESCRIPTION
  248. .PP
  249. \fBTcl_CreateCommand\fR defines a new command in \fIinterp\fR and associates
  250. it with procedure \fIproc\fR such that whenever \fIcmdName\fR is
  251. invoked as a Tcl command (via a call to \fBTcl_Eval\fR) the Tcl interpreter
  252. will call \fIproc\fR
  253. to process the command.  If there is already a command \fIcmdName\fR
  254. associated with the interpreter, it is deleted.  \fIProc\fP should
  255. have arguments and result that match the type \fBTcl_CmdProc\fR:
  256. .nf
  257. .RS
  258. typedef int Tcl_CmdProc(
  259. .RS
  260. ClientData \fIclientData\fR,
  261. Tcl_Interp *\fIinterp\fR,
  262. int \fIargc\fR,
  263. char *\fIargv\fR[]);
  264. .RE
  265. .RE
  266. .fi
  267. When \fIproc\fR is invoked the \fIclientData\fP and \fIinterp\fR
  268. parameters will be copies of the \fIclientData\fP and \fIinterp\fR
  269. arguments given to \fBTcl_CreateCommand\fR.
  270. Typically, \fIclientData\fR points to an application-specific
  271. data structure that describes what to do when the command procedure
  272. is invoked.  \fIArgc\fR and \fIargv\fR describe the arguments to
  273. the command, \fIargc\fR giving the number of arguments (including
  274. the command name) and \fIargv\fR giving the values of the arguments
  275. as strings.  The \fIargv\fR array will contain \fIargc\fR+1 values;
  276. the first \fIargc\fR values point to the argument strings, and the
  277. last value is NULL.
  278. .PP
  279. \fIProc\fR must return an integer code that is either \fBTCL_OK\fR, \fBTCL_ERROR\fR,
  280. \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.  See the Tcl overview man page
  281. for details on what these codes mean.  Most normal commands will only
  282. return \fBTCL_OK\fR or \fBTCL_ERROR\fR.  In addition, \fIproc\fR must set
  283. \fIinterp->result\fR to point to a string value;
  284. in the case of a \fBTCL_OK\fR return code this gives the result
  285. of the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
  286. The \fBTcl_SetResult\fR procedure provides an easy interface for setting
  287. the return value;  for complete details on how the \fIinterp->result\fR
  288. field is managed, see the \fBTcl_Interp\fR man page.
  289. Before invoking a command procedure,
  290. \fBTcl_Eval\fR sets \fIinterp->result\fR to point to an empty string, so simple
  291. commands can return an empty result by doing nothing at all.
  292. .PP
  293. .VS
  294. The contents of the \fIargv\fR array belong to Tcl and are not
  295. guaranteed to persist once \fIproc\fR returns:  \fIproc\fR should
  296. not modify them, nor should it set \fIinterp->result\fR to point
  297. anywhere within the \fIargv\fR values.
  298. Call \fBTcl_SetResult\fR with status \fBTCL_VOLATILE\fR if you want
  299. to return something from the \fIargv\fR array.
  300. .VE
  301. .PP
  302. \fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted.
  303. This can occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR,
  304. or by replacing \fIcmdName\fR in another call to \fBTcl_CreateCommand\fR.
  305. \fIDeleteProc\fR is invoked before the command is deleted, and gives the
  306. application an opportunity to release any structures associated
  307. with the command.  \fIDeleteProc\fR should have arguments and
  308. result that match the type \fBTcl_CmdDeleteProc\fR:
  309. .nf
  310. .RS
  311. .sp
  312. typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
  313. .sp
  314. .RE
  315. .fi
  316. The \fIclientData\fR argument will be the same as the \fIclientData\fR
  317. argument passed to \fBTcl_CreateCommand\fR.
  318. .PP
  319. \fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
  320. Once the call completes, attempts to invoke \fIcmdName\fR in
  321. \fIinterp\fR will result in errors.
  322. If \fIcmdName\fR isn't bound as a command in \fIinterp\fR then
  323. \fBTcl_DeleteCommand\fR does nothing and returns -1;  otherwise
  324. it returns 0.
  325. There are no restrictions on \fIcmdName\fR:  it may refer to
  326. a built-in command, an application-specific command, or a Tcl procedure.
  327. .PP
  328. .VS
  329. \fBTcl_GetCommandInfo\fR checks to see whether its \fIcmdName\fR argument
  330. exists as a command in \fIinterp\fR.  If not then it returns 0.
  331. Otherwise it places information about the command in the structure
  332. pointed to by \fIinfoPtr\fR and returns 1.
  333. Tcl_CmdInfo structures have fields named \fIproc\fR, \fIclientData\fR,
  334. and \fIdeleteProc\fR, which have the same meaning as the corresponding
  335. arguments to \fBTcl_CreateCommand\fR.
  336. There is also a field \fIdeleteData\fR, which is the ClientData value
  337. to pass to \fIdeleteProc\fR;  it is normally the same as
  338. \fIclientData\fR but may be set independently using the
  339. \fBTcl_SetCommandInfo\fR procedure.
  340. .PP
  341. \fBTcl_SetCommandInfo\fR is used to modify the procedures and
  342. ClientData values associated with a command.
  343. Its \fIcmdName\fR argument is the name of a command in \fIinterp\fR.
  344. If this command exists then \fBTcl_SetCommandInfo\fR returns 0.
  345. Otherwise, it copies the information from \fI*infoPtr\fR to
  346. Tcl's internal structure for the command and returns 1.
  347. Note that this procedure allows the ClientData for a command's
  348. deletion procedure to be given a different value than the ClientData
  349. for its command procedure.
  350. .VE
  351.  
  352. .SH KEYWORDS
  353. bind, command, create, delete, interpreter
  354.